docs: add Podman provider documentation#285
Conversation
- Replace Buildah build attribution with accurate `podman build` phrasing - Add UID hint for PODMAN_HOST socket path examples - Use `id -u` in troubleshooting socket example - Simplify provider registration description
- Replace podman machine init --rootful with sudo podman (Linux page) - Demote heading levels to match existing ### hierarchy - Remove macOS/Windows guidance from Linux troubleshooting page
✅ Deploy Preview for devsydev ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
📝 WalkthroughWalkthroughThis PR adds comprehensive documentation for Podman as a 1st-party Devsy provider. It repositions Podman from community status to the default provider list, introduces a new setup tutorial covering cross-platform installation and configuration, and provides Linux-specific troubleshooting for socket, compose, build, and permission issues. ChangesPodman Provider Documentation
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~4 minutes Suggested labels
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/pages/troubleshooting/linux-troubleshooting.mdx`:
- Around line 94-95: Change the absolutist sentence that "Files created inside
the container appear owned by `nobody` on the host" to a softened statement:
note that Rootless Podman maps UIDs via user namespaces and files on the host
can show as `nobody` or as other numeric UIDs/GIDs depending on the system's
subuid/subgid mappings; update the paragraph beginning "Rootless Podman maps
UIDs through user namespaces." to reflect this variability and mention checking
subuid/subgid configuration when ownership looks unexpected.
In `@docs/pages/tutorials/podman-provider-setup.mdx`:
- Around line 57-61: The text "Verify the socket is reachable from Windows" is
misleading because the shown command (echo $XDG_RUNTIME_DIR/podman/podman.sock)
runs in WSL and only prints the Linux-side path; update Step 3 wording to
clarify the execution context by stating that the command should be run inside
WSL (or the Linux environment) to display the socket path and separately
instruct how to confirm Windows can reach that socket (for example by
translating the path or testing with a Windows-side client), and keep the
example command `echo $XDG_RUNTIME_DIR/podman/podman.sock` as the WSL-specific
step.
- Around line 145-149: Replace the in-workspace check that tells users to run
"podman --version" (which can fail because workspace images may not include the
Podman CLI) with provider/runtime verification commands: instruct users to run
"devsy provider list" to confirm the provider is Podman and/or run "podman ps"
on the host to inspect running containers; update the text around the former
"podman --version" mention to show these alternative commands ("devsy provider
list" and "podman ps") and remove the in-container Podman version check.
- Line 180: Replace the inaccurate sentence that claims "podman compose" is "a
built-in subcommand backed by the `podman-compose` Python library" with neutral
wording stating that Podman v4+ includes the `podman compose` command and that
it is compatible with `docker-compose` v2 syntax for most workloads; update the
paragraph containing the phrase "podman compose" so it no longer asserts a
specific backing provider and instead notes that the backing provider can vary.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 68820df8-c2cc-4ae8-b0a3-cf6cd8da7f52
📒 Files selected for processing (4)
docs/pages/managing-providers/add-provider.mdxdocs/pages/troubleshooting/linux-troubleshooting.mdxdocs/pages/tutorials/podman-provider-setup.mdxdocs/sidebars.js
| Rootless Podman maps UIDs through user namespaces. Files created inside the container appear owned by `nobody` on the host. | ||
|
|
There was a problem hiding this comment.
Make ownership outcome less absolute.
Line 94 says files appear as nobody, but rootless mappings can appear as different numeric UIDs/GIDs depending on subuid/subgid setup. Soften wording to avoid inaccurate troubleshooting expectations.
Suggested doc tweak
-Rootless Podman maps UIDs through user namespaces. Files created inside the container appear owned by `nobody` on the host.
+Rootless Podman maps UIDs through user namespaces. Files created inside the container may appear owned by an unexpected UID/GID (sometimes shown as `nobody`) on the host.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Rootless Podman maps UIDs through user namespaces. Files created inside the container appear owned by `nobody` on the host. | |
| Rootless Podman maps UIDs through user namespaces. Files created inside the container may appear owned by an unexpected UID/GID (sometimes shown as `nobody`) on the host. | |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/pages/troubleshooting/linux-troubleshooting.mdx` around lines 94 - 95,
Change the absolutist sentence that "Files created inside the container appear
owned by `nobody` on the host" to a softened statement: note that Rootless
Podman maps UIDs via user namespaces and files on the host can show as `nobody`
or as other numeric UIDs/GIDs depending on the system's subuid/subgid mappings;
update the paragraph beginning "Rootless Podman maps UIDs through user
namespaces." to reflect this variability and mention checking subuid/subgid
configuration when ownership looks unexpected.
| **Step 3 — Verify the socket is reachable from Windows.** Note the socket path — you will need it for the `PODMAN_HOST` option: | ||
|
|
||
| ```bash | ||
| echo $XDG_RUNTIME_DIR/podman/podman.sock | ||
| ``` |
There was a problem hiding this comment.
Clarify execution context for the socket check.
Line 57 says “reachable from Windows,” but the command shown is executed in WSL and only prints the Linux-side socket path. Rewording avoids confusion.
Suggested doc tweak
-**Step 3 — Verify the socket is reachable from Windows.** Note the socket path — you will need it for the `PODMAN_HOST` option:
+**Step 3 — Verify the Podman socket path inside WSL.** Note this path — you will need it for the `PODMAN_HOST` option:🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/pages/tutorials/podman-provider-setup.mdx` around lines 57 - 61, The
text "Verify the socket is reachable from Windows" is misleading because the
shown command (echo $XDG_RUNTIME_DIR/podman/podman.sock) runs in WSL and only
prints the Linux-side path; update Step 3 wording to clarify the execution
context by stating that the command should be run inside WSL (or the Linux
environment) to display the socket path and separately instruct how to confirm
Windows can reach that socket (for example by translating the path or testing
with a Windows-side client), and keep the example command `echo
$XDG_RUNTIME_DIR/podman/podman.sock` as the WSL-specific step.
| A successful `devsy ssh` connection confirms the workspace is running under Podman. To verify the Podman binary inside the workspace: | ||
|
|
||
| ```bash | ||
| podman --version | ||
| ``` |
There was a problem hiding this comment.
Use a provider/runtime verification step instead of checking podman inside the workspace.
Line 145 suggests podman --version inside the workspace, but workspace containers often won’t include Podman CLI. This can produce a false failure in an otherwise-correct setup.
Suggested doc tweak
-A successful `devsy ssh` connection confirms the workspace is running under Podman. To verify the Podman binary inside the workspace:
+A successful `devsy ssh` connection confirms the workspace is running. To verify Podman is the active runtime, check from the host:
```bash
-podman --version
+devsy provider list
+# or inspect running containers with:
+podman ps</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
A successful `devsy ssh` connection confirms the workspace is running. To verify Podman is the active runtime, check from the host:
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/pages/tutorials/podman-provider-setup.mdx` around lines 145 - 149,
Replace the in-workspace check that tells users to run "podman --version" (which
can fail because workspace images may not include the Podman CLI) with
provider/runtime verification commands: instruct users to run "devsy provider
list" to confirm the provider is Podman and/or run "podman ps" on the host to
inspect running containers; update the text around the former "podman --version"
mention to show these alternative commands ("devsy provider list" and "podman
ps") and remove the in-container Podman version check.
|
|
||
| ### `podman compose` vs `docker-compose` | ||
|
|
||
| Podman v4+ ships `podman compose` as a built-in subcommand backed by the `podman-compose` Python library. It is compatible with `docker-compose` v2 syntax for most workloads. If your `devcontainer.json` or workspace scripts call `docker-compose` directly, replace those calls with `podman compose` or create a shell alias: |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
According to official Podman documentation, is podman compose always a built-in implementation, or does it delegate to external providers (such as docker-compose or podman-compose) depending on configuration/version?
💡 Result:
Yes. Per the official Podman documentation, podman compose is “a thin wrapper around an external compose provider” (e.g., docker-compose or podman-compose), and it passes the specified options plus the command/arguments directly to that provider. By default, the compose providers are docker-compose and podman-compose, with docker-compose taking precedence if installed. The provider can be changed via the compose_providers setting in containers.conf(5) (or the PODMAN_COMPOSE_PROVIDER environment variable), so it is not always a built-in implementation of Compose itself; it delegates to whichever external provider is configured/available. [1]
Citations:
Remove inaccurate claim about podman compose implementation.
Line 180 states that podman compose is "a built-in subcommand backed by the podman-compose Python library." According to official Podman documentation, podman compose is a thin wrapper around external compose providers (such as docker-compose or podman-compose), not a built-in implementation. The backing provider is configurable and not always podman-compose. Use neutral wording that focuses on compatibility instead:
Podman v4+ includes the
podman composecommand, which is compatible withdocker-composev2 syntax for most workloads.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/pages/tutorials/podman-provider-setup.mdx` at line 180, Replace the
inaccurate sentence that claims "podman compose" is "a built-in subcommand
backed by the `podman-compose` Python library" with neutral wording stating that
Podman v4+ includes the `podman compose` command and that it is compatible with
`docker-compose` v2 syntax for most workloads; update the paragraph containing
the phrase "podman compose" so it no longer asserts a specific backing provider
and instead notes that the backing provider can vary.
1 participant
Summary
docs/pages/tutorials/podman-provider-setup.mdx— comprehensive Podman provider setup guide covering Linux, macOS, and Windows prerequisites, provider registration, configuration options (PODMAN_PATH, PODMAN_HOST, INACTIVITY_TIMEOUT), rootless vs rootful setup, workspace creation, and troubleshootingdocs/pages/managing-providers/add-provider.mdx— moved from community providers list to the built-in providers list with link toproviders/podmandocs/sidebars.jsfor the new tutorialdocs/pages/troubleshooting/linux-troubleshooting.mdxcovering rootless socket paths, podman compose compatibility, BuildKit/buildah differences, and volume mount permissions in rootless modeCloses DEVSY-101.
Summary by CodeRabbit